From 2024384e0a8ec26a3a335958bc6a107ba87a7efc Mon Sep 17 00:00:00 2001 From: "Jasper St. Pierre" Date: Mon, 13 May 2013 15:11:41 -0400 Subject: [PATCH] Add some usage docs for the new private copy/paste APIs --- gtk/gtkmenutracker.c | 34 ++++++++++++++++++++++++++ gtk/gtkmenutrackeritem.c | 52 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+) diff --git a/gtk/gtkmenutracker.c b/gtk/gtkmenutracker.c index ba8c4b9b10..ab369ab02f 100644 --- a/gtk/gtkmenutracker.c +++ b/gtk/gtkmenutracker.c @@ -23,6 +23,40 @@ #include "gtkmenutracker.h" +/** + * SECTION:gtkmenutracker + * @Title: GtkMenuTracker + * @Short_description: A helper class for interpreting #GMenuModel + * + * #GtkMenuTracker is a simple object to ease implementations of #GMenuModel. + * Given a #GtkActionObservable (usually a #GActionMuxer) along with a + * #GMenuModel, it will tell you which menu items to create and where to place + * them. If a menu item is removed, it will tell you the position of the menu + * item to remove. + * + * Using #GtkMenuTracker is fairly simple. The only guarantee you must make + * to #GtkMenuTracker is that you must obey all insert signals and track the + * position of items that #GtkMenuTracker gives you. That is, #GtkMenuTracker + * expects positions of all the latter items to change when it calls your + * insertion callback with an early position, as it may ask you to remove + * an item with a readjusted position later. + * + * #GtkMenuTracker will give you a #GtkMenuTrackerItem in your callback. You + * must hold onto this object until a remove signal is emitted. This item + * represents a single menu item, which can be one of three classes: normal item, + * separator, or submenu. + * + * Certain properties on the #GtkMenuTrackerItem are mutable, and you must + * listen for changes in the item. For more details, see the documentation + * for #GtkMenuTrackerItem along with https://live.gnome.org/GApplication/GMenuModel. + * + * The idea of @with_separators is for special cases where menu models may + * be tracked in places where separators are not available, like in toplevel + * "File", "Edit" menu bars. Ignoring separator items is wrong, as #GtkMenuTracker + * expects the position to change, so we must tell #GtkMenuTracker to ignore + * separators itself. + */ + typedef struct _GtkMenuTrackerSection GtkMenuTrackerSection; struct _GtkMenuTracker diff --git a/gtk/gtkmenutrackeritem.c b/gtk/gtkmenutrackeritem.c index 3c6e8f54a8..1755f6ed2f 100644 --- a/gtk/gtkmenutrackeritem.c +++ b/gtk/gtkmenutrackeritem.c @@ -23,6 +23,58 @@ #include "gtkmenutrackeritem.h" +/** + * SECTION:gtkmenutrackeritem + * @Title: GtkMenuTrackerItem + * @Short_description: Small helper for model menu items + * + * A #GtkMenuTrackerItem is a small helper class used by #GtkMenuTracker to + * represent menu items. It has one of three classes: normal item, separator, + * or submenu. + * + * If an item is one of the non-normal classes (submenu, separator), only the + * label of the item needs to be respected. Otherwise, all the properties + * of the item contribute to the item's appearance and state. + * + * Implementing the appearance of the menu item is up to toolkits, and certain + * toolkits may choose to ignore certain properties, like icon or accel. The + * role of the item determines its accessibility role, along with its + * decoration if the GtkMenuTrackerItem::toggled property is true. As an + * example, if the item has the role %GTK_MENU_TRACKER_ITEM_ROLE_CHECK and + * GtkMenuTrackerItem::toggled is %FALSE, its accessible role should be that of + * a check menu item, and no decoration should be drawn. But if + * GtkMenuTrackerItem::toggled is %TRUE, a checkmark should be drawn. + * + * All properties except for the two class-determining properties, + * GtkMenuTrackerItem::is-separator and GtkMenuTrackerItem::has-submenu are + * allowed to change, so listen to the notify signals to update your item's + * appearance. When using a GObject library, this can conveniently be done + * with g_object_bind_property() and #GBinding, and this is how this is + * implemented in GTK+; the appearance side is implemented in #GtkModelMenuItem. + * + * When an item is clicked, simply call gtk_menu_tracker_item_activated() in + * response. The #GtkMenuTrackerItem will take care of everything related to + * activating the item and will itself update the state of all items in + * response. + * + * Submenus are a special case of menu item. When an item is a submenu, you + * should create a submenu for it with gtk_menu_tracker_new_item_for_submenu(), + * and apply the same menu tracking logic you would for a toplevel menu. + * Applications using submenus may want to lazily build their submenus in + * response to the user clicking on it, as building a submenu may be expensive. + * + * Thus, the submenu has two special controls -- the submenu's visibility + * should be controlled by the GtkMenuTrackerItem::submenu-shown property, + * and if a user clicks on the submenu, do not immediately show the menu, + * but call gtk_menu_tracker_item_request_submenu_shown() and wait for the + * GtkMenuTrackerItem::submenu-shown property to update. If the user navigates, + * the application may want to be notified so it can cancel the expensive + * operation that it was using to build the submenu. Thus, + * gtk_menu_tracker_item_request_submenu_shown() takes a boolean parameter. + * Use %TRUE when the user wants to open the submenu, and %FALSE when the + * user wants to close the submenu. + */ + typedef GObjectClass GtkMenuTrackerItemClass; struct _GtkMenuTrackerItem -- 2.30.2